Administrator Guide 2017
Create a Word report

Step 1. Create a Word document skeleton

  1. Make a copy of an existing Word document or open a blank document.  Many of the form templates provided with magic5 have Word templates already attached.  These can be opened by clicking on the List entries of the Word templates list.  Clicking on the link for the Word document associated with your template (or the closest match) will open it in Word.
       
  2. As you can see, these are simple generic forms, although they include powerful functionality of both magic5 and Word.  The example used below, however, is based on a bespoke audit document - there is no reason why the styles of one cannot be transferred to the other.
  3. If starting from a blank document, you will probably include a static header for customer details and, maybe, fixed text (such as an explanation of terms, references, conditions, regulations, etc) followed by an area for data as collected on the device and a closing area including (for example) signatures, dates, summaries.  There may also be appendices such as supporting evidence, photographs, plans, references, etc.
  4. Check (using Print Preview) that the pagination is appropriate and that borders make things easy to read.  This will probably need to be done again later so don't spend too long on it now.
  5. Think about how the magic5 data is going to populate the skeleton.


    The example shown is for a Risk Assessment Report. 
    • The first page contains information supplied by the office such as customer and site details, and can include a customer specific image filled in by magic5 as well as your company logo as a fixed picture set up in Word.
    • This is followed by a Table of Contents which will be created using Word's reference tools.  It is linked to Heading Styles defined and used within the document - as can be seen in the example below, this example uses Heading 1 style for main ToC entries and Heading 2 for sub-items.  Word allows more levels than this and a number of ready made formats are available.
    • The footer can also be set up to contain a brief document description using magic5 variables and Word fields - the example below contains customer name and assessment date and would normally include a page number set up in Word.  It is worth noting that page numbering in Word can be made much more flexible by using Sections and starting the page number afresh with each section - this is particularly useful for Page X of Y as Y can be set to refer to a Section rather than Document count.
    • The next page contains a number of fixed items that will appear on all reports - this might be clarification of terms, regulatory text, outline of procedure, disclaimers, generic introductions, etc.
    • This is followed by the data collected on the device.  In this example the data is findings which require a special bookmark that will be explained below, but it is more often single data items and often a simple yes or no from multiple choice.

Step 2. Set up data collection items in the template

  1. If you are unsure about creating templates go to Template for help on setting one up.
  2. Enter meaningful unique names for your template items and make a note of them. These are usually located in the 'Advanced' tab of the edit box.  The example here uses 'JobNo', utilising capital letters to clarify the meaning as spaces are not allowed, although underscore ("_") and hyphens ("-") are.  Please also note that they are case sensitive so this example would not be recognised as "jobno".

  3. Note down the attributes and unique names that you have used for your template items, remembering that they are case sensitive.
  4. In the above example, unique names are used for sections to facilitate formatted output and iterations.

Step 3. Enter the unique names in the Word document

  1. Use Word's Mail Merge field to enter template items and attributes, referring back to the unique names and attributes noted down in Step 2.  

    Merge fields can be inserted into a Word document by selecting the Insert tab then Quick Parts and choosing Field.  In the Field dialogue box, select MergeField from the Field names list on the left and type in the unique name or attribute name as shown below.
  2. As shown below, variables are prefixed with a $ sign using the syntax
    $[variable name]
    eg $Customer
  3. Attributes are joined with their corresponding entity, identified by the variable name in the following syntax:
    $[variable name]:[attribute name]
    eg $Customer:phoneNumber
  4. The full variable list includes: 
    • Customer
    • Location
    • UserFullName
    • LocationAddress
    • CustomerAddress
    • LocationAddressFlat (ie. no line breaks, uses commas)
    • CustomerAddressFlat (ditto)

  5. As a point of interest, customer and location addresses can be entered as either variables ($CustomerAddress and $LocationAddress respectively) or as attributes ($Customer:address and $Location:address respectively).
  6. Template items are identified by the unique name as identified in Step 2.

Step 4. (optional) Create special fields in the Word document

  1. For repeating areas (such as repeating sections), the entries in Step 3 are adequate for the first occurence but subsequent iterations needs to be suffixed with
    ___n (ie 3 x '_'). 
    The first occurence has an implicit suffix of ___0, whilst subsequent iterations have ___1, ___2, etc.
  2. Repeating sections or an unspecified number of rows in a magic5 table can be output by entering the unique name in each position (eg Word table cell) and entering the following as a separate mergefield (see step 3) at the start of the repeating area:
    RangeStart:[unique name of section or table]
    and the following at the end
    RangeEnd:[unique name of section or table]

    For example, the following is from a table in a Word document into which the data from a repeating section called fuelSources is to be entered.  The first template item has a unique name of fuelSource, the next fuelSourceLocation and the last fuelCurrentControlMeasure.
  3. In a table, a row can be conditionally removed using the statement
    $delTR_[unique name of a multiple choice item]_[multiple choice answer]
    This can be positioned anywhere in the conditional row. 
    A repeating item (as in 3 above) needs to replace the underscore ("_") with a hyphen ("-")
    $delTR-[unique name of a multiple choice item including suffix]_[multiple choice answer]
  4. A whole table can be conditionally removed using a similar syntax of
    $delTABLE_[unique name of a multiple choice item]_[multiple choice answer]
    $delTABLE-[unique name of a mandatory item within repeating area including suffix]-[multiple choice answer]
    (note the use of hyphen instead of underscore when using a repeating item).
  5. $delTABLE and $delTR can also be used to remove a table or a row if when an item contains no data (ie is 'null') using the syntax
    $delTABLE_[unique name of item]   or   $delTR_[unique name of item]  
    or   $delTABLE-[unique name of item plus iteration suffix]   or $delTR-[unique name of item plus iteration suffix]
  6. Output all Findings, Follow-ups and Timescales plus any text entry or photo items within a section using the syntax
    SectionFindings_[unique name of section]
    To omit the text entry items use
    SectionFindingsNoComments_[unique name of section]
  7. Ticks be set up using the syntax
    $tick_[unique name of template item]_[answer to trigger the tick]
    eg $tick_ClearWalkway_Yes
  8. Similarly, a cross can be set using the syntax
    $cross_[unique name of template item]_[answer to trigger the cross]
    eg $cross_ClearWalkway_No
  9. magic5 uses bookmarks in Word to create powerful formatting and options. The following are available:
    • CustomerLogo will output an image associated with the customer for whom the report has been produced.
    • ActionPlan will output tables containing the actions associated with any findings in the report.  These tables are organised by timescales as contained in the timescales list associated with the template.  The style ActionPlanHeading is required for this bookmark.
    • DrawingLocation will output an annotated image as identified within the template using the Drawing Location item type
    • SectionFindings will output all the findings, actions, timescales, text items and photos within a section.  The unique name of the section is required in the syntax
      SectionFindings_[unique name]
    • SectionFindingsNoComments will output all the findings, actions, timescales and photos but not the text items.  Again the unique name of the section is required in the syntax
      SectionFindingsNoComments_[unique name]
    • Signature will output the signature of a signature item type.  The unique name is required in the syntax
      Signature_[unique name]
    • SHOWIF_rV will conditionally show the area enclosed by the bookmark.  The unique name of the item type that creates the condition is required and the value to test is also required in the syntax SHOWIF_rV_[unique name]_eq_[result value]. 

      If this is a list item, the value to test will be the id rather than the text of the item (shown on the righthand side of the list of list entries).

      For example, if a multiple-choice question (unique name='ShowSection') of Yes (id=69) or No (id=70) is asked to ascertain whether a section should be shown on the report, the bookmark would be
      SHOWIF_ShowSection_eq_69
      so that it would only appear if the Yes answer had been selected
    • Photos will output all the photos collected on the form.  If there are no photos the text 'No supporting photographs' will be shown.
  10. Insert bookmarks at the points where special items (such as customer logos and signatures) are to appear.
  11. Ensure that any requisite styles have been created.  The style can be whatever you require but suggested starting points for the example used here are given below.
    • Action - based on the Normal style with with a 'tick box' style bullet.  This enables the recipient of the document to tick of actions as they are completed. 
    • FindingsHeading - Similar to a heading style.  This will contain the word 'Observations'.
    • Observation - based on the Normal style with a solid bullet.  This differentiates it from the actions as they do not need to be ticked off.
    • Timescale - based on the Normal style in bold and right alignment so that they can be easily distinguished from the rest of the text.
    • ActionPlanHeading - Similar to a heading style. This will contain the timescale at the head of each action plan table (usually displayed at the end of the report).

Step 5. Add document to list of Word Templates

  1. If not already there, create a list called Word Templates and give it attributes of:
    • Code assembly and class (advanced)
    • Template file name
    • Text on button
    • Additional settings
    • Associated document or image

  2. If FTP uploading is being used, upload the document to the correct folder on the server. If this makes no sense to you then it is irrelevant.
  3. Create a list entry, giving it a meaningful name in the Text prompt.  Other items on the main List Entry tab are irrelevant here.
  4. In the Additional Attributes tab, fill in the following:
    • If NOT using FTP (see 2 above), upload the Word document using Add attachment and Select to browse your computer for the correct Word document
    • If FTP is being used, enter the correct filename in Template file name
    • Enter appropriate text for the button that will appear on the Report screen to initiate the Word document and enter the name of the document uploaded in step 3 in Template file name.
    • Additional settings requires specific keywords for unusual circumstances.  If you have particular needs, magic5 support might ask you to enter specific text here.
           

Step 6. Attach the Word document to the Template

  1. Open the parameters of the required template and select the Report tab.  Under Word template, select the list entry created in step 5 from the drop-down list. 
  2. More than one Word Template can be attached to the magic5 template and each will be initiated by a separate button at the bottom of the report screen.